-
Notifications
You must be signed in to change notification settings - Fork 145
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: conform docstrings to PEP257 #365
Conversation
See: https://peps.python.org/pep-0257/#multi-line-docstrings Break argument descriptions into separate chunks, and make them more direct. Also, remove a Python2 compatibility fossil.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The docs build fails on RTD because it lacks a .readthedocs.yaml
. See https://readthedocs.org/projects/colander/builds/24402967/
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fixes a few typos and reST and English syntax.
I noticed there is inconsistency between the use of **strong**
and *emphasis*
. In pylons-sphinx-themes
, text with a bold font style is indistinguishable from normal text, due to the chosen font family. I recommend using *emphasis*
instead.
From Pyramid docs, this snippet:
* **Workspaces, projects, and packages.** Our home directory will contain a
*tutorial workspace* with our Python virtual environment and *Python
projects* (a directory with packaging information and *Python packages* of
working code.)
Renders as:
https://docs.pylonsproject.org/projects/pyramid/en/latest/quick_tutorial/requirements.html
Note that strong (bold) face renders slightly blurry for normal text, whereas emphasis renders clearly in italic.
Also, now that I've finally figured out how to design Sphinx themes, I created a theme for Plone that could be adapted for Pylons Projects.
Co-authored-by: Steve Piercy <web@stevepiercy.com>
Co-authored-by: Steve Piercy <web@stevepiercy.com>
Co-authored-by: Steve Piercy <web@stevepiercy.com>
Co-authored-by: Steve Piercy <web@stevepiercy.com>
Co-authored-by: Steve Piercy <web@stevepiercy.com>
Co-authored-by: Steve Piercy <web@stevepiercy.com>
Co-authored-by: Steve Piercy <web@stevepiercy.com>
Co-authored-by: Steve Piercy <web@stevepiercy.com>
Co-authored-by: Steve Piercy <web@stevepiercy.com>
Co-authored-by: Steve Piercy <web@stevepiercy.com>
afd5d0d
to
3a35224
Compare
See: https://peps.python.org/pep-0257/#multi-line-docstrings
Break argument descriptions into separate chunks, and make them more direct.
Also, remove a Python2 compatibility fossil.